---
title: Cloudinary & Astro
description: Añade imágenes y vídeos a tu proyecto Astro usando Cloudinary
sidebar:
  label: Cloudinary
type: media
stub: true
logo: cloudinary
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';

[Cloudinary](https://cloudinary.com) es una plataforma de imágenes y vídeos y un Gestor de Activos Digitales (DAM) headless que te permite alojar activos y entregarlos desde su red de distribución de contenido (CDN).

Al entregar desde Cloudinary, adicionalmente obtienes acceso a su API de Transformación, dándote la capacidad de editar tus activos con herramientas como eliminación de fondo, recorte y redimensionamiento dinámico, e IA generativa.

## Usando Cloudinary en Astro

Cloudinary soporta una amplia variedad de SDKs que pueden ser utilizados dependiendo de tu entorno Astro.

El [SDK de Cloudinary para Astro](https://astro.cloudinary.dev/) proporciona componentes nativos de Astro, incluyendo componentes de imagen, vídeo y carga, así como un cargador de contenido que puede ser utilizado con las colecciones de contenido de Astro.

Alternativamente, tanto el [SDK de Node.js](https://cloudinary.com/documentation/node_integration) como el [SDK de JavaScript](https://cloudinary.com/documentation/javascript_integration) de Cloudinary pueden ser utilizados para generar URLs para tus imágenes. El SDK de Node.js puede adicionalmente realizar peticiones a la API de Cloudinary, incluyendo la carga de activos, solicitud de recursos y análisis de contenido.

## Prerrequisitos

- Un proyecto Astro existente
- Una cuenta de Cloudinary

## Instalando Astro Cloudinary

Instala el SDK de Cloudinary para Astro ejecutando el comando apropiado para tu gestor de paquetes:

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install astro-cloudinary
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add astro-cloudinary
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add astro-cloudinary
  ```
  </Fragment>
</PackageManagerTabs>

## Configurando tu cuenta

Crea un nuevo archivo `.env` en la raíz de tu proyecto y añade tus credenciales de Cloudinary:

```shell title=".env"
PUBLIC_CLOUDINARY_CLOUD_NAME="<Tu Nombre de Nube>"

// Solo necesario si usas CldUploadWidget o cldAssetsLoader
PUBLIC_CLOUDINARY_API_KEY="<Tu Clave API>"
CLOUDINARY_API_SECRET="<Tu Secreto API>"
```

## Usando imágenes de Cloudinary

Añade imágenes en componentes `.astro` pasando datos de imagen (por ejemplo, `src`, `width`, `alt`) al componente `<CldImage>`. Esto optimizará automáticamente tu imagen y te dará acceso a la API de Transformaciones.

```jsx title="Component.astro"
---
import { CldImage } from 'astro-cloudinary';
---
<CldImage
  src="<ID Público>"
  width="<Ancho>"
  height="<Alto>"
  alt="<Descripción>"
/>
```

Consulta la [documentación de `<CldImage>` de Cloudinary](https://astro.cloudinary.dev/cldimage/basic-usage) para más información.

## Usando vídeos de Cloudinary

Para añadir vídeo a tus componentes `.astro`, añade el `<CldVideoPlayer>` y pasa las propiedades apropiadas. Este componente optimizará e incrustará automáticamente tu vídeo usando el [Reproductor de Vídeo de Cloudinary](https://cloudinary.com/documentation/cloudinary_video_player).

```jsx title="Component.astro"
---
import { CldVideoPlayer } from 'astro-cloudinary';
---
<CldVideoPlayer
  src="<ID Público>"
  width="<Ancho>"
  height="<Alto>"
/>
```

Consulta la [documentación de `<CldVideoPlayer>` de Cloudinary](https://astro.cloudinary.dev/cldvideoplayer/basic-usage) para más información.

## Habilitando cargas de Cloudinary

Para habilitar la carga de archivos en la interfaz de tu sitio web o aplicación, añade el `<CldUploadWidget>` que incrustará el [Widget de Carga de Cloudinary](https://cloudinary.com/documentation/upload_widget).

El siguiente ejemplo crea un widget para permitir cargas sin firmar pasando un [Preset de Carga](https://cloudinary.com/documentation/upload_presets) sin firmar:

```jsx title="Component.astro"
---
import { CldUploadWidget } from 'astro-cloudinary';
---
<CldUploadWidget uploadPreset="<Preset de Carga>">
  <button>Cargar</button>
</CldUploadWidget>
```

Para cargas firmadas, puedes encontrar [una guía y ejemplo](https://astro.cloudinary.dev/clduploadwidget/signed-uploads) en la documentación de Astro Cloudinary.

Consulta la [documentación de `<CldUploadWidget>` de Cloudinary](https://astro.cloudinary.dev/clduploadwidget/basic-usage) para más información.

## Cargador de contenido de Cloudinary

El SDK de Cloudinary para Astro proporciona el cargador de contenido `cldAssetsLoader` para cargar activos de Cloudinary para colecciones de contenido.

Para cargar una colección de imágenes o vídeos, establece `loader: cldAssetsLoader ({})` con una `folder`, si es necesario:

```jsx title="config.ts"
import { defineCollection } from 'astro:content';
import { cldAssetsLoader } from 'astro-cloudinary/loaders';

export const collections = {
  assets: defineCollection({
    loader: cldAssetsLoader({
      folder: '<Carpeta>' // Opcional, sin ella carga el directorio raíz
    })
  }),
}
```

Luego puedes usar las [funciones de consulta `getCollection()` o `getEntry()`](/es/guides/content-collections/#querying-collections) para seleccionar una o varias imágenes o vídeos de tu colección.

Consulta la [documentación de `cldAssetsLoader` de Cloudinary](https://astro.cloudinary.dev/cldassetsloader/basic-usage) para más información.

## Generando URLs de imágenes de Cloudinary

El SDK de Cloudinary para Astro proporciona un ayudante `getCldOgImageUrl()` para generar y usar URLs para tus imágenes. Usa esto cuando necesites una URL en lugar de un componente para mostrar tu imagen.

Un uso común para una URL es para una imagen Open Graph en etiquetas `<meta>` para tarjetas de redes sociales. Este ayudante, como los componentes, te proporciona acceso a las transformaciones de Cloudinary para crear tarjetas sociales dinámicas y únicas para cualquiera de tus páginas.

El siguiente ejemplo muestra las etiquetas `<meta>` necesarias para una tarjeta de redes sociales, usando `getCldOgImageUrl()` para generar una imagen Open Graph:

```jsx title="Layout.astro"
---
import { getCldOgImageUrl } from 'astro-cloudinary/helpers';
const ogImageUrl = getCldOgImageUrl({ src: '<ID Público>' });
---
<meta property="og:image" content={ogImageUrl} />
<meta property="og:image:secure_url" content={ogImageUrl} />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="twitter:title" content="<Título de Twitter>" />
<meta property="twitter:card" content="summary_large_image" />
<meta property="twitter:image" content={ogImageUrl} />
```


Encuentra [Plantillas de Tarjetas de Redes Sociales de Cloudinary](https://astro.cloudinary.dev/templates/social-media-cards) en la documentación de Cloudinary.

Consulta la [documentación de `getCldOgImageUrl()` de Cloudinary](https://astro.cloudinary.dev/getcldogimageurl/basic-usage) para más información.

## Usando Cloudinary en Node.js

Para una gestión de activos más compleja, carga o análisis, puedes usar el SDK de Node.js de Cloudinary cuando trabajas en un entorno Node.js de Astro.

Instala el SDK de Node.js de Cloudinary ejecutando el comando apropiado para tu gestor de paquetes:

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install cloudinary
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add cloudinary
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add cloudinary
  ```
  </Fragment>
</PackageManagerTabs>

Añade las siguientes variables de entorno en tu archivo `.env`:

```shell title=".env"
PUBLIC_CLOUDINARY_CLOUD_NAME="<Tu Nombre de Nube>"
PUBLIC_CLOUDINARY_API_KEY="<Tu Clave API>"
CLOUDINARY_API_SECRET="<Tu Secreto API>"
```

Configura tu cuenta con una nueva instancia de Cloudinary añadiendo el siguiente código entre las vallas de tu componente Astro:

```js title="Component.astro"
---
import { v2 as cloudinary } from "cloudinary";

cloudinary.config({
  cloud_name: import.meta.env.PUBLIC_CLOUDINARY_CLOUD_NAME,
  api_key: import.meta.env.PUBLIC_CLOUDINARY_API_KEY,
  api_secret: import.meta.env.CLOUDINARY_API_SECRET,
});
---
```

Esto te dará acceso a todas las APIs de Cloudinary para permitirte interactuar con tus imágenes, vídeos y otros archivos soportados.

```js title="Component.astro"
await cloudinary.uploader.upload('./path/to/file');
```

Aprende cómo [cargar archivos usando el SDK de Node.js de Cloudinary con Formularios de Astro](https://www.youtube.com/watch?v=DQUYMyT2MTM).


## Recursos Oficiales

- [SDK de Cloudinary para Astro](https://astro.cloudinary.dev/)
- [SDK de Node.js de Cloudinary](https://cloudinary.com/documentation/node_integration)
- [Usando Cloudinary con Astro (YouTube)](https://www.youtube.com/playlist?list=PL8dVGjLA2oMqnpf2tShn1exf5GkSWuu5-)
- [Ejemplos de Código Usando el SDK de Cloudinary para Astro (GitHub)](https://github.com/cloudinary-community/cloudinary-examples/tree/main/examples/astro-cloudinary)
